Skip to content

chore(options): deprecate flatten: false and schedule the option for removal in 0.22 - #709

Merged
route merged 1 commit into
fix/raw-event-yields-paramsfrom
deprecate-flatten
Nov 20, 2026
Merged

route merged 1 commit into
fix/raw-event-yields-paramsfrom
deprecate-flatten

Conversation

@route

@route route commented Nov 20, 2026

Copy link
Copy Markdown
Member

What

Ferrum::Browser.new(flatten: false) now warns that the option will be removed in 0.22. Passing true or nothing stays silent, and the behavior of both modes is unchanged until then.

Why

  • flatten: false is not CDP's non-flat mode. Target.setAutoAttach and Target.attachToTarget always pass flatten: true, the option only makes each target open an extra websocket to /devtools/page/<id> on top of its session on the browser connection.
  • That second transport has no spec coverage and takes different paths than the default, e.g. the missing session check in Target#build_worker.
  • The per-target URL is built by swapping the path of the browser's ws_url, which assumes the endpoint routes /devtools/page/<id>.
  • Chrome's protocol marks non-flat sessions as deprecated, and a pipe transport has a single channel, so sharing the browser connection is the only mode worth keeping.

Changes

  • Browser::Options warns once per call site when flatten: false is passed
  • YARD, docs/2-customization.md, RBS and the changelog note the deprecation

@route
route force-pushed the deprecate-flatten branch from 7e0ced7 to 00b4597 Compare November 20, 2026 06:51
@route
route changed the base branch from main to fix/raw-event-yields-params November 20, 2026 06:54
@route
route merged commit eb90145 into fix/raw-event-yields-params Nov 20, 2026
7 checks passed
@route
route deleted the deprecate-flatten branch November 20, 2026 07:39
route added a commit that referenced this pull request Nov 20, 2026
* ref(events): yield only the params to raw CDP event callbacks

The dispatcher passed each callback its index and the total number of callbacks, leaking subscriber internals into on and breaking lambdas and symbol procs taking one argument. Tracing relied on the index and ignored Tracing.tracingComplete unless its callback came first, so a user subscription added before the first record made it time out.

* chore(options): deprecate flatten: false and schedule the option for removal in 0.22 (#709)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant